Directory names are filtered in-place (dir_names[:]) to prevent
traversal into excluded directories.

Args:
    top_dir: The starting directory for the walk. Defaults to the current directory.

Yields:
    Relative file path strings (e.g., 'src/module/file.py').
"""
for dir_path, dir_names, filenames in os.walk(top_dir):
    # 1. Prune directory names (in-place modification of dir_names)
    # Excludes: Hidden directories (starting with '.'), common excluded names, and directories starting with '_'
    dir_names[:] = [
        d
        for d in dir_names
        if d[0] not in "._" and d not in EXCLUDED_DIRS
    ]

    # 2. Iterate over files and yield good paths
    for filename in filenames:
        # Skip module initialization files
        if filename == "__init__.py":
            continue

        # Check for valid extensions
        _, ext = os.path.splitext(filename)
        if ext in (".py", ".ipynb"):
            # Clean up path to ensure it doesn't start with './'
            full_path = os.path.join(dir_path, filename)
            yield full_path.lstrip("./")

Level 0 (no indent) generates a top-level header.
Level > 0 generates a bullet point indented by 2 spaces per level.

Args:
    indent_level: The depth of the current item (0 for root, 1 for first level).

Returns:
    The markdown prefix string.
"""
if indent_level == 0:
    # Markdown H2 header for root-level entries
    return "\n##"
# Indent with 2 spaces per level for nested lists (e.g., 2 spaces for level 1, 4 for level 2)
return f"{' ' * (indent_level * 2)}*"

Args:
    top_dir: The root directory to start the scan.
"""
# Stores the path of the last directory printed to determine new structure levels
last_printed_path = ""

# Get and sort all file paths to ensure consistent output order
sorted_file_paths = sorted(good_file_paths(top_dir))

for filepath in sorted_file_paths:
    # Separate the directory path from the filename
    current_dir_path, filename = os.path.split(filepath)

    # --- Directory Structure Printing ---
    if current_dir_path != last_printed_path:
        # Path segments of the previous and current directory
        old_parts = last_printed_path.split(os.sep)
        new_parts = current_dir_path.split(os.sep)

        # Determine where the new path structure begins
        # 'i' tracks the indent level and the common prefix length
        i = 0
        while i < len(old_parts) and i < len(new_parts) and old_parts[i] == new_parts[i]:
            i += 1

        # Print the new directory segments
        for indent, new_part in enumerate(new_parts[i:], start=i):
            if new_part: # Ensure we don't print empty segments
                prefix = _generate_markdown_prefix(indent)
                print(f"{prefix} {_format_name(new_part)}")

        # Update the last printed path for the next comparison
        last_printed_path = current_dir_path

    # --- File Entry Printing ---
    # The indent for the file is one level deeper than its parent directory.
    indent = (current_dir_path.count(os.sep) + 1) if current_dir_path else 0

    # Create the URL-encoded path for the Markdown link
    url = filepath.replace(" ", "%20")

    # Format the filename for display (excluding extension)
    display_name = os.path.splitext(_format_name(filename))[0]

    prefix = _generate_markdown_prefix(indent)
    print(f"{prefix} [{display_name}]({url})")